home *** CD-ROM | disk | FTP | other *** search
/ Computer Select (Limited Edition) / Computer Select.iso / pcmag / v11n09 / bd1.exe / PROTOC.TXT < prev   
Text File  |  1992-04-22  |  9KB  |  223 lines
  1. Writing a new protocol
  2.  
  3. If you want to add a new protocol to BACKDOWN, here is a
  4. description of the interface that BACKDOWN uses to communicate
  5. with protocol modules.
  6.  
  7. First, BACKDOWN searches for potential protocol modules by
  8. scanning for *.BDP files in the directory indicated by the BDP
  9. environment variable.  If the environment variable is not set, it
  10. searches the current directory.
  11.  
  12. When BACKDOWN finds a matching file, it opens that file and reads
  13. the first six bytes looking for the characters "BD" in fourth and 
  14. fifth byte.  If found, BACKDOWN uses the sixth byte to identify the 
  15. number of protocols implemented in the module. Then it reads the 
  16. associated headers into memory.  The "Protocol Module Header" code 
  17. segment in Figure A shows the header for the XMODEM protocol module 
  18. where two protocols are implemented.  BACKDOWN cannot use another 
  19. program's protocol modules because they do not adhere to BACKDOWN's 
  20. user interface and are not designed to run in the background.
  21. During the search, BACKDOWN notes the length of the longest
  22. protocol module and subsequently reserves enough memory to
  23. accommodate it.
  24.  
  25. When a protocol is invoked, BACKDOWN loads the module into memory
  26. with the opening jump statement aligned on a paragraph boundary
  27. (an address evenly divisible by 16.) BACKDOWN then calls the
  28. module with a far call to (segment address:0), allowing the
  29. protocol module easy addressability to its local variables and
  30. buffers. Refer to Figure B for the protocol module calling
  31. conventions.
  32.  
  33. The entry section describes register contents when BACKDOWN calls
  34. the protocol module.  This is how BACKDOWN tells the protocol
  35. module of an event occurring. There are four events
  36. that BACKDOWN passes to the module: Initialization, keyboard,
  37. character receive, and simple dispatch.
  38.  
  39. The initialization event occurs as soon as the module is loaded.
  40. It should only happen once and all of the protocol modules
  41. supplied with BACKDOWN fail if initialization is invoked a second
  42. time. During this event, the module may prepare to receive a 
  43. download, but this will vary from protocol to protocol.  For instance, 
  44. the XMODEM protocol opens the receive file and sends a NAK to the 
  45. host, while the B+ protocol it simply sets up a few variables and 
  46. returns.
  47.  
  48. The keyboard event is called only if BACKDOWN is popped up and
  49. the user presses a key.  The module may process the key or
  50. discard it.
  51.  
  52. BACKDOWN issues a character receive event when a character is
  53. available in the communications receive buffer.  Most of a
  54. module's life is spent waiting for these events.
  55.  
  56. Finally, the simple dispatch event gives the module a chance to
  57. run and determine if an error condition (such as a timeout) has 
  58. occurred.
  59.  
  60. Unlike the typical subroutine, protocol modules do not simply
  61. return so BACKDOWN can continue running.  More appropriately, a
  62. module returns with a request code directing BACKDOWN to do some
  63. work.  This mechanism frees you from worrying about how to do
  64. file or communications I/O in the background and lets you
  65. concentrate on implementing the protocol.
  66.  
  67. When the protocol module returns to BACKDOWN, the DI register
  68. contains the request code that directs BACKDOWN's next action.
  69. Except for request codes 0 (No request) and 10 (Done), BACKDOWN
  70. performs the requested action and calls the module with function
  71. code 2 (Previous request successful) or 4 (Previous function
  72. failed). It is up to the protocol module to remember where it was
  73. when it returned to BACKDOWN with a request code.
  74.  
  75. Some request codes pass a string to BACKDOWN by putting the offset of
  76. the string within the protocol module into the BX register.
  77. In the case of request codes 4 (Write file) and 18 (Send string
  78. out on COM port), the area referenced must start with a word
  79. containing the number of bytes to process, directly followed by
  80. the bytes.
  81.  
  82. When the module returns with request code 0 (No request), it
  83. tells BACKDOWN that the protocol module has no more work to do
  84. for now, and that it can go look for another event.  When the
  85. module returns with request code 10 (Done), BACKDOWN unloads the
  86. protocol module and returns control to the dumb terminal or
  87. script.  If the protocol module did not issue an explicit close,
  88. the receive file will be closed when the protocol module return
  89. with code 10.
  90.  
  91. -- Bob Flanders
  92.  
  93. *************************Figure A**********************************
  94.  
  95. ; ---------------------------------------------------------------
  96. ;
  97. ;  Example of a protocol module header
  98. ;
  99. ; The first 3 bytes are a jump statement to the body of the
  100. ; module. The next two are the letters "BD" which BACKDOWN
  101. ; uses to identify its protocol modules.
  102. ;
  103. ; Following the identifier is a byte indicating the number of
  104. ; protocols supported by this module, in this case, two
  105. ; protocols.
  106. ;
  107. ; Immediately following the count byte is one or more 19 byte
  108. ; descriptors that identify the protocols supported.
  109. ;
  110. ; The first byte of the descriptor is a letter used to invoke the
  111. ; protocol.  Next is a 16 byte description of the module followed
  112. ; by a single zero byte, making it an ASCIIZ string.  Finally,
  113. ; the last byte is a number that will be passed to the module
  114. ; when it is invoked with the corresponding letter.  This lets
  115. ; the module know which protocol the user requested to invoke
  116. ; this module.
  117. ;
  118. ; ---------------------------------------------------------------
  119.  
  120.  
  121. start:      jmp     bpmxmodem               ; jump to start
  122.             db      "BD"                    ; BACKDOWN protocol
  123. ID
  124.  
  125.             db      2                       ; number of protocols
  126.  
  127.             db      "X"                     ; invocation letter
  128.             db      "Xmodem V1.0     ", 0   ; name to display
  129.             db      1                       ; protocol number
  130.  
  131.             db      "C"                     ; invocation letter
  132.             db      "Xmodem/CRC V1.0 ", 0   ; name to display
  133.             db      2                       ; protocol number
  134.  
  135.  
  136.  
  137. *************************Figure B**********************************
  138.  
  139.   Entry:   ax = current tick downcounter
  140.            di = function code
  141.            cs = the module's segment
  142.            ds = caller's segment
  143.  
  144.       Function: 0 = initialization call
  145.  
  146.                 ds:bx contains address of any operands
  147.                       given after the script letter. The operands
  148.                       are passed as ASCIIZ strings.
  149.  
  150.                 dx contains protocol number from the header
  151.  
  152.                 si contains the offset in BACKDOWN of a 10 byte
  153.                    work area. (This is needed for BPLUS protocol)
  154.  
  155.                 2 = Dispatch or Previous request successful
  156.  
  157.                 4 = Last request failed
  158.  
  159.                 6 = Communications character received
  160.  
  161.                     dl: Received Character
  162.  
  163.                 8 = Keystroke detected
  164.  
  165.                     dl: character or 0
  166.                     dh: scan code
  167.  
  168.  
  169.      Exit: di = Request code
  170.            ds, es, ss and sp are restored to entry values.
  171.  
  172.  
  173.         Request
  174.         Code:    0 = No request
  175.  
  176.                  2 = Open output file
  177.  
  178.                      bx: offset in module of ASCIIZ string
  179.                          containing filename to open
  180.  
  181.                  4 = Write file
  182.  
  183.                      bx: offset in module of buffer
  184.  
  185.                  6 = Close file
  186.  
  187.                  8 = Delete file
  188.  
  189.                      bx: offset in module of ASCIIZ string
  190.                          containing filename to delete
  191.  
  192.                 10 = Done. Module will be unloaded.
  193.  
  194.                 12 = Display an ASCIIZ string, <CR>'s translated
  195.  
  196.                      bx: Offset in module of string to display
  197.  
  198.                 14 = Display one character, <CR>'s translated
  199.  
  200.                      bl: Character to display
  201.  
  202.                 16 = Get a line (max 64 chars)
  203.  
  204.                      bx: Offset in module of buffer for line.
  205.  
  206.                 18 = Send string out on COM port
  207.  
  208.                      bx: offset in module of buffer
  209.  
  210.                 20 = Send single character out on